Wie kann Künstliche Intelligenz den Entwurf von APIs unterstützen – besonders dann, wenn das eigene Fachwissen an Grenzen stößt? Dieser Artikel zeigt, wie KI und Domain-Driven Design gemeinsam zu besseren Architekturen führen.

Der Entwurf von Software im Allgemeinen und von Application Programming Interfaces (APIs) im Besonderen ist ein Prozess, in dem IT-Spezialisten und Businessexperten eng zusammenarbeiten müssen. Dieser Prozess kann durch Workshopformate wie Event Storming [1] und Domain Storytelling [2] effektiv unterstützt werden. In der Folge können sowohl strategische als auch taktische Softwarearchitekturen entwickelt werden. Der Synergetic-Blueprint-Prozess [3] gibt diesem Entwurfsprozess eine klare Struktur und unterstützt alle Beteiligten dabei, ihre Ziele effizient zu erreichen.

Abbildung 1 zeigt den Synergetic-Blueprint-Prozess. Er beginnt mit der Festlegung des geschäftlichen Ziels im Rahmen der Unternehmensarchitektur. Das kann beispielsweise mit Hilfe eines Business-Model-Canvas [4] erfolgen. Im Anschluss werden die erforderlichen Geschäftsfähigkeiten definiert, die dann über eine Wardley Map [5] priorisiert werden.

Die Domain wird durch die Methoden Domain Storytelling und Event Storming definiert. Dadurch ergeben sich auch die zu implementierenden Bounded Contexts (Kasten „Bounded Context“). Um die Ubiquitous Language (Kasten: „Ubiquitous Language“) festzulegen, nutzen Businessexperten und IT-Spezialisten ein visuelles Glossar, das auch als Visual Glossary bezeichnet wird (wir gehen weiter unten darauf ein).

Das Service-Design wird über eine Context Map (Kasten „Context Map“) definiert. Sie wird ebenfalls benutzt, um den notwendigen Datenaustausch und damit die notwendigen APIs zu definieren. Das taktische Design setzt sich im Sinne der Definition des Domänenmodells innerhalb des Bounded Context und des Datenbankdesigns unter Benutzung der Ubiquitous Language fort. Dieser Aspekt wird im vorliegenden Artikel nicht behandelt. Daher ist er auch in Abbildung 1 nicht dargestellt.

Wir wollen allerdings darauf eingehen, wie man aus der Context Map ein API-Design ableiten kann. Hierfür kann das API Product Canvas [9] benutzt werden.

API Product Canvas

Das API Product Canvas wurde entwickelt, um in Workshops mit IT-Spezialisten und Business-Experten über API-Designs zu diskutieren. Es fokussiert sich auf einen Bounded Context, idealerweise auf einen Service, der eine spezifische Geschäftsfunktion implementiert [10]. Das Template ist technologieunabhängig gestaltet, sodass für die synchrone Kommunikation REST, gRPC oder auch andere Protokolle und für die asynchrone Kommunikation Kafka, MQSeries oder andere Varianten benutzt werden können.

Abbildung 2 zeigt ein Beispiel für ein API Product Canvas. Es enthält den Bounded Context „Catalog Management“ mit REST-Schnittstellen für die synchrone und Kafka-Events für die asynchrone Kommunikation.

Das Canvas umfasst einen Headerbereich, einen Abschnitt für die synchrone Kommunikation, einen Abschnitt für asynchrone Kommunikation sowie einen Footerbereich.

Im Headerbereich werden Informationen zur typischen Funktion im Businessprozess (Value Proposition), zu den implementierten Funktionen und den Kontaktinformationen bereitgestellt, wie sie typischerweise im Infoblock von API-Definitionen auftreten [11], [12]. Der Abschnitt für die Serverkomponente, sowohl für die asynchrone als auch die synchrone Kommunikation, enthält das gewählte Protokoll sowie den Zugriffslink.

Das gewählte Beispiel eines Katalogmanagements einer Onlinebibliothek enthält REST-Schnittstellen, um Katalogeinträge zu manipulieren. Die Pfade, um sowohl auf Katalogeinträge mit Suchparametern als auch auf einzelne Katalogeinträge mit ihrem Identifier zuzugreifen, sind als blaue Bänder gekennzeichnet. Zusätzlich zu den Katalogeinträgen mit ihren Parametern kann über die Pfade auf Zusammenfassungen (Abstracts) und auf Stichwörter (Tags) zugegriffen werden. Die einzelnen Pfade enthalten die implementierten HTTP-Methoden und die zu erwartenden Antworten. Diese Informationen werden idealerweise aus einer Context Map [3] abgeleitet.

Der Abschnitt für die asynchrone Kommunikation enthält die Domänen-Events, die einen Datenaustausch triggern, sowie die entsprechende Payload, die beim Auftreten des Events übertragen wird. Die Events werden nach empfangenen und gesendeten unterschieden. Der Service „Catalog Management“ sendet z. B. ein Event „Catalog Entry Created“, wenn ein neuer Katalogeintrag erzeugt wurde. Das Event enthält dann die Informationen eines Katalogeintrags als Payload. Der Fußbereich des Canvas enthält wichtige architektonische Informationen und Festlegungen.

Das Canvas kann sehr gut in Workshops eingesetzt werden, um gemeinsam mit IT-Spezialisten und Businessexperten APIs von Bounded Contexts zu diskutieren. Idealerweise bringen Teilnehmer schon Kenntnisse aus vorangegangenen Workshops des Synergetic-Blueprint-Prozesses mit [3]. Das Canvas kann aber auch unabhängig von vorangegangenen Workshops eingesetzt werden [9].

Das API generieren

Ein solches diskutiertes API Product Canvas kann benutzt werden, um die entsprechenden API-Definitionen zu generieren. Der Prompt soll die Spezialität der Aufgabe, die Vorgehensweise und das Ziel enthalten. Weiterhin ist es hilfreich für die Generierung, ein Beispiel für das erwartete Ergebnis zur Verfügung zu stellen. Diese Vorgehensweise wird auch als One-Shot-Prompt bezeichnet [13]. Das Prompt aus Listing 1 kann benutzt werden, um aus dem API Product Canvas eine OpenAPI-Definition zu erzeugen [14].

You are a specialized OpenAPI 3.1.0 Generator Assistant. You help users create a complete API specification for Catalog Management by analyzing: 
1. Images of API Product Canvas diagrams showing endpoints, methods, and parameters
2. YAML examples of OpenAPI specifications for reference 
When these files are uploaded, you will: 
1. Carefully analyze the images to extract API endpoint information and data models 
2. Use visual recognition to identify endpoints, HTTP methods, parameters, and responses 
3. Use the YAML example as a template for formatting and organization
4. Generate a complete, valid OpenAPI 3.1.0 specification combining all this information
For image analysis: - Look for boxes, arrows, labels, and other visual elements that indicate API endpoints and data structures - Identify HTTP methods (GET, POST, PUT, DELETE, etc.), typically color-coded or labeled - Extract path parameters (usually in {curly braces}) - Note response codes and data types.
If information in the images is unclear, make reasonable assumptions based on API best practices and explain your decisions. Always validate your final OpenAPI specification against 3.1.0 standards before presenting it.

Auf den ersten Blick sieht das Ergebnis [15] zufriedenstellend aus. Allerdings gibt es auch Kritikpunkte. So kann ein Katalogeintrag nur einen Autor haben, und das Publikationsjahr ist als Integer modelliert (Listing 2). Um solche Fehler zu vermeiden, kann in der Diskussion von IT-Spezialisten und Businessexperten ein Visual Glossary [16] eingesetzt werden.

author:
  type: string
  minLength: 1
  maxLength: 200
  description: Author of the book
publicationYear:
type: integer
  minimum: 1000
  maximum: 2100
  description: Year of publication

Visual Glossary

Ein visuelles Glossar oder Visual Glossary erläutert Begriffe und kann gleichzeitig verwendet werden, um die Ubiquitous Language eines Bounded Context zu definieren. Im Gegensatz zu einem klassischen Glossar werden die Begriffe nicht in langen Tabellen, sondern in ihrer Beziehung zueinander erläutert. Das geschieht visuell, indem die Begriffe über starke Verben verbunden werden. Zusätzlich können Kardinalitäten hinzugefügt werden. Zum Beispiel kann man Tisch und Bein dadurch erläutern, dass „Bein“ mit 3..4 „Tisch“ trägt. Damit ähnelt es Domänenmodellen, die mit der Unified Modelling Language (UML) modelliert wurden. Allerdings sind die Modelle expressiver, da sie starke Verben verwenden, die über die in UML definierten Beziehungen wie „aggregiert“ hinausgehen.

Bezogen auf unser Beispiel heißt das, dass IT-Spezialisten und Businessexperten das Modell des Katalogmanagements gemeinsam diskutieren können.

Das API mit API Product Canvas und Visual Glossary generieren

Abbildung 3 zeigt das Visual Glossary für das Katalogmanagement. Zusätzlich zu den Begriffen kann das Glossar zweisprachig ausgeführt werden, um auch deutsche Begriffe im Glossar mitzuführen. Das Prompt muss durch die Anforderung der Interpretation des visuellen Glossars erweitert werden (Listing 3) [17].

Listing 3: Prompt-Erweiterung

1. Images of API Product Canvas diagrams showing endpoints, methods, and parameters
2. Images of Visual Glossary diagrams illustrating data structures and relationships
3. YAML examples of OpenAPI specifications for reference
When these files are uploaded, you will: 
1. Carefully analyze the images to extract API endpoint information and data models 
2. Use visual recognition to identify endpoints, HTTP methods, parameters, and responses 
3. Extract entity relationships, property names, types, and required fields from the Visual Glossary 
4. Use the YAML example as a template for formatting and organization
5. Generate a complete, valid OpenAPI 3.1.0 specification combining all this information

Das generierte Modell entspricht nun besser dem, das mit Businessexperten diskutiert wurde (Listing 4) [18].

CatalogEntry:
  type: object
  required:
    - id
    - title
    - authors
    - isbn
    - publisher
    - publishedOn
    - createdAt
    - updatedAt
  properties:
    id:
      type: string
      format: uuid
      description: Unique identifier for the catalog entry
    title:
      type: string
      minLength: 1
      maxLength: 500
      description: Title of the book or publication
    authors:
      type: array
      items:
        type: string
        minLength: 1
        maxLength: 200
      minItems: 1
      maxItems: 10
      description: Authors of the publication (at least one required)

Das Modell sowie das OpenAPI müssen weiter verfeinert und optimiert werden. Insbesondere verwenden die Schemas für CatalogEntry, CatalogEntryCreate und CatalogEntryUpdate keine Vererbung über allOf, was den Code strukturierter und besser verständlich machen würde. Zudem sollten die Beschreibungen der Schemas und der einzelnen Properties angepasst werden, um ausführlicher und klarer formuliert zu sein.

Insgesamt ist die Generierung des OpenAPI jedoch lohnend, da sie auf einer gemeinsam erarbeiteten Ubiquitous Language und einer konsensbasierten Funktionalität basiert, die im API Product Canvas dokumentiert ist. Diese Generierung stellt einen hervorragenden Ausgangspunkt für die weitere Entwicklung dar, da sie die Ergebnisse des Workshops aufgreift und die monotonen Tätigkeiten beim Schreiben von Code übernimmt.

Das API aus einer Context Map generieren

Basis für das API Product Canvas ist eine Context Map [8], die innerhalb von Workshops mit IT-Spezialisten und Businessexperten erarbeitet werden kann. Diese Context Map kann durch Datenaustauschinformationen erweitert werden.

Abbildung 4 zeigt hierfür ein Beispiel.

Die Context Map zeigt die Bounded Contexts „Purchase“, „Audio Summary“, „Catalog Management“ und „Catalog Search“. „Catalog Search“ fungiert als Conformist (CF) zu „Catalog Management“, was bedeutet, dass das durch „Catalog Management“ definierte Modell von „Catalog Search“ übernommen wird. Alle anderen Bounded Context Services sind als Open-Host-Services (OHS) konzipiert. Das heißt, dass sie als eigenständige Services existieren können, die ihre Modelle selbst definieren und über eine Published Language (PL) veröffentlichen.

Die Services untereinander kommunizieren asynchron über entsprechende Events. Diese sind mit dem Event-Namen und der entsprechenden Payload als gestrichelte Linien gekennzeichnet. Ein Service kann seine Funktionalitäten für externe Zugriffe wie z. B. einen mobilen Client über synchrone Aufrufe verfügbar machen. Diese sind als HTTP-Verben (Get, Post, Put, Delete) [19] am Bounded Context gekennzeichnet.

Auch aus der Context Map können API-Definitionen generiert werden. Der Prompt, um ein AsyncAPI [12] für das Contact-Management zu generieren, ist in Listing 5 aufgeführt [20], [21].

Prompt: Create an AsyncAPI for Catalog Management from Context Map, Visual Glossary, and Example
You are a specialist in API design using AsyncAPI 3.0.0. I will provide three inputs:
A Context Map (image) – This illustrates the bounded contexts and their relationships.
A Visual Glossary (image) – This shows the domain language, aggregates, entities, and value objects used within a specific context.
An Example Async Specification (YAML) – This is a partial or similar API spec that shows formatting, structure, and naming conventions to follow.
Your task: Generate a complete and well-structured AsyncAPI 3.0.0 specification for the bounded context Catalog Management that is the focus of the Visual Glossary. Use the terminology and modeling from the Glossary. Follow the style and structure of the Example AsyncAPI. Use the Context Map to:
Understand boundaries and integrations.
Annotate potential external APIs as $refs or externalDocs.
Identify what should not be included (e.g., concepts owned by other contexts).
Guidelines:
Follow AsyncAPI 3.0.0 strictly.
All schema names must reflect the domain language from the Glossary.
Structure the paths, components, and tags similarly to the example YAML.
Annotate cross-context interactions using externalDocs or description fields.

Das Ergebnis ist zufriedenstellend und bietet eine exzellente Grundlage für die Verfeinerung der Spezifikation. Die notwendigen zu konsumierenden und zu produzierenden Events werden erkannt, und das Binding an das gewählte Protokoll erfolgt korrekt gemäß der Vorlage (Listing 6). Die Schemas müssen jedoch überarbeitet und gestrafft werden.

Wie immer bei asynchroner Kommunikation sollte sorgfältig überlegt werden, ob alle Eigenschaften der übertragenen Payload tatsächlich erforderlich sind. Beispielsweise könnte man im Katalogeintrag auf die Zusammenfassung (Abstract) verzichten, da diese nur in Ausnahmefällen benötigt wird und dann synchron nachgeladen werden kann.

BookPurchasedChannel:
  description: Channel where book purchased events are received from Purchase context
  address: book-purchased
  messages:
    BookPurchasedEvent:
      $ref: '#/components/messages/BookPurchasedReceive'
  bindings:
    kafka:
      topic: 'book-purchased-event-channel'
      bindingVersion: '0.5.0'

CatalogEntryCreatedChannel:
  description: Channel where catalog entry created events are published
  address: catalog-entry-created
  messages:
    CatalogEntryCreatedEvent:
      $ref: '#/components/messages/CatalogEntryCreatedSend'
  bindings:
    kafka:
      topic: 'catalog-entry-created-event-channel'
      bindingVersion: '0.5.0'

CatalogEntryUpdatedChannel:
  description: Channel where catalog entry updated events are published
  address: catalog-entry-updated
  messages:
    CatalogEntryUpdatedEvent:
      $ref: '#/components/messages/CatalogEntryUpdatedSend'
  bindings:
    kafka:
      topic: 'catalog-entry-updated-event-channel'
      bindingVersion: '0.5.0'

CatalogEntryDeletedChannel:
  description: Channel where catalog entry deleted events are published
  address: catalog-entry-deleted
  messages:
    CatalogEntryDeletedEvent:
      $ref: '#/components/messages/CatalogEntryDeletedSend'
  bindings:
    kafka:
      topic: 'catalog-entry-deleted-event-channel'
      bindingVersion: '0.5.0'

Für synchrone APIs ist aus Erfahrung der Autorin die Context Map nicht präzise genug. Die notwendigen Endpunkte werden nur grob erkannt. Insbesondere werden notwendige Subressourcen wie in unserem Beispiel Tags und Abstracts nicht oder es werden zu viele erzeugt.

Zusammenfassung und Ausblick

API-Generatoren großer LLMs können effektiv zur Erstellung einer ersten Version einer API-Definition genutzt werden. Das funktioniert jedoch nur zufriedenstellend, wenn die Ergebnisse aus Workshops als Eingabedaten für die Generatoren verwendet werden. Zudem sind gut ausgearbeitete Vorlagen für das erwartete Ergebnis erforderlich, um befriedigende Resultate zu erzielen.

LLMs eignen sich als Startpunkt für die API-Definition, wenn die Diskussion zwischen Businessexperten und IT-Spezialisten unter Verwendung von DDD-Workshopformaten die Ubiquitous Language und die zu erwartende Funktionalität klar festgelegt haben.

Im nächsten Teil der Artikelserie beschäftigen wir uns mit der Unterstützung der LLMs in den Workshopformaten vom Businessmodell bis zum Event-Storming-Ergebnis.